Set up an agreement

The setup agreement step validates the cardholder details and stores securely the credentials on file, so that they can be used in subsequent transactions many times without a need to be reintroduced by the customer.

The diagram below describes a typical setup agreement flow using the Merchant API.

You can set up an agreement using one of the following methods:

  • /createPaymentRequest

    • Along with the other mandatory parameters described in the createPaymentRequest page, when set up the agreement using createPaymentRequest API method, you should specify the type parameter. See below the possible values.

      curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/createPaymentRequest \
  --header 'Authorization: Basic auth' \
  --data type=subscription \
  --data `agreement[type]`=recurring \
  --data 'terminal=Pensio Terminal' \
  --data shop_orderid=abc123 \
  --data amount=50 \
  --data currency=EUR \
  • /setupSubscription

    • Use the setupSubscription method as a shortcut for calling the reservation method with type = subscription for payments using the full credit card details.

    The method has the exact same parameter specification as reservation, but the type parameter is always set to subscription, even if you specify a different type in the method call.

      curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/setupSubscription \
  --header 'Authorization: Basic auth' \
  --data type=subscription \
  --data `agreement[type]`=unscheduled \
  --data 'terminal=Pensio Terminal' \
  --data shop_orderid=abc123 \
  --data amount=50 \
  --data currency=EUR \
  --data cardnum=4111111111111111 \
  --data emonth=08 \
  --data eyear=2025 \
  --data cvc=123 \
  • VerifyCard as Unscheduled Charges

    • It is possible to use the verifyCard to set up unscheduled charges agreement.

    See VerifyCard as Unscheduled Charges for more details.


The following table describes the required parameters when set up an agreement

The following list does not represent the complete list of the parameters used when set up an agreement. For the entire list of the parameters, please check the parameters list of every setup agreement method described above.

Select from the drop-down list to see the parameters relevant for that method/acquirer:

Parameter Description Type Mandatory
type

This is the authorization type.

Below you can find more details about the type parameter and the possible values.

 string Yes, excepting the case when setting up the agreement using /setupSubscription method.
agreement[type]

This is the type of the agreement.

Below you can find more details about the agreement[type] parameter and the possible values.

 string No. Recurring value will be used in case the parameter is not set.
agreement[unscheduled_type]

This is the type of the unscheduled agreement.

Below you can find more details about the agreement[unscheduled_type] parameter and the possible values.

 string Only in case the type is subscriptionAndCharge or subscriptionAndReserve and the agreement[type]=unscheduled.
agreement[expiry]

This is the date when the agreement expires. It must have the format YYYYMMDD.

 string No.
agreement[frequency]

It is an integer value representing the frequency between the charge agreement requests made by the merchant. Possible values: 0 - Flexible; 1 - Daily; 7 - Weekly; 14 - Biweekly; 30 - Monthly; 90 - Quarterly; 365 - Yearly.

 string No. Default Value: Monthly for recurring/instalment, Flexible for unscheduled. Default Value: Flexible
Not allowed for unscheduled agreement.
agreement[next_charge_date]

This is the date of the first charge agreement request made by the merchant. It must have the format YYYYMMDD..

 string No
agreement[admin_url]

This is a link to a page on the merchant side where the customer can manage the agreement.

 string NoYes
agreement[retention_period]

The customer will be able to cancel the agreement only after passing this retention period.

 string No
customer_info[customer_phone]

This is the customer phone number. Used to improve customer experience.

 string Recommended for a good customer experience.
orderLines

The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience.

See details here

One order line with the following parameters is required for Vipps integration in order to ensure a good customer experience.

Value

Description

Type

description

Description of the agreement.

String (255)

itemId

The name of the product for which the agreement is created.

String (100)

UnitPrice and quantity parameters might be required for this order line, but that parameters are not relevant to the Create Vipps agreement request.

One order line with the following parameters is required for MobilePay integration in order to ensure a good customer experience.

Value

Description

Type

description

Description of the agreement.

String (255)

itemId

Used to define Plan parameter. Short Agreement information text, that will be displayed on the Agreement screen in the app. (examples: “Basic” / “Premium”).

String (100)

UnitPrice and quantity parameters might be required for this order line, but that parameters are not relevant to the Create Vipps agreement request.

 Array NoYes

Subscription type

When setting up a new agreement, you can decide whether to just set up the agreement, or set it up and immediately create a reservation or charge for the created agreement, using the type parameter on the call: 

Payment request type

Description

subscription

The payment is part of an agreement. The agreement is set up, and the payment is authorized immediately, but as a merchant, you have to capture each instalment separately using the captureReservation or chargeSubscription method, or using the Merchant Information Interface.

subscriptionAndCharge

The agreement is set up, and an attempt is made to capture the first instalment payment.

The XML response has two <Transaction> elements. If either the agreement setup or the capture is successful, the <Result> XML response parameter is set to Success, even if the other transaction fails. This means that you cannot rely solely on the <Result> parameter to determine whether the transaction was successful.

subscriptionAndReserve

The agreement is set up, and an attempt is made to reserve the first instalment payment.

Not all acquirers support this. For more information, see Payment methods and providers.

If either the agreement setup, or the reservation is successful, the <Result> XML response parameter is set to Success, even if one of the transactions fail. The XML response has two <Transaction> elements. This means that you cannot rely solely on the <Result> parameter to determine whether the transaction was successful.

Agreement type

When setting up a new agreement, you can decide what kind of agreement you want to create, using the agreement[type] parameter on the call:

Agreement type

Description

recurring

Allows the merchant to charge the customer with a specific frequency and in most cases with a specific amount, in exchange for fixed goods or services.

Default. If no agreement[type] is provided, recurring will be used.

When set up a recurring agreement, the Strong Customer Authentication takes place.

instalment

Allows the merchant to charge the customer for goods or services billed to a cardholder in multiple transactions, over a period of time agreed with the cardholder.

When set up an instalment agreement, the Strong Customer Authentication takes place.

unscheduled

Allows the merchant to charge the customer for goods or services that do not follow a specific frequency, neither have a fixed amount to be paid out.

When only setting up an unscheduled agreement "authType=subscription", you can use 0 as amount in order to avoid charging customer. If you're intending to reserve/charge right away, please use the right amount in the request.

When set up an unscheduled agreement, the Strong Customer Authentication takes place.

Unscheduled type

In case the type parameter is subscriptionAndCharge or subscriptionAndReserve and the agreement[type]=unscheduled, the agreement[unscheduled_type] parameter is mandatory.

Unshceduled type

Description

incremental

An incremental authorisation is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. A common scenario is additional services charged to the contract, such as extending a stay in a hotel.

For the incremental authorisation, the cardholder authentication is not required.

resubmission

This is an event that occurs when the original purchase occurred but the Merchant was not able to get authorisation at the time the goods or the services were provided.

For the resubmission authorisation, the cardholder authentication is not required.

delayedCharges

A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered.

For the delayed charge authorisation, the cardholder authentication is not required.

reauthorisation

A reauthorisation is a purchase made after the original purchase. A common scenario is delayed/split shipments.

For the reauthorisation, the cardholder authentication is not required.

noShow

A no-show is a transaction where the merchant are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement.

For the no-show authorisations, the cardholder authentication is not required.

charge

A transaction using a Stored Credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds.

For the charge authorisations, the Strong Customer Authentication takes place.

Response Examples

Here is an example of the XML response when the agreement setup succeeds, but the first charge fails. The XML response is posted to the fail page (callback_fail).

There are two transactions, one with AuthType set to subscriptionAndCharge, representing the agreement, and one with AuthType set to subscription_payment, representing the first agreement payment.

The Result parameter in the XML response says Success, but the TransactionStatus of the agreement payment is captured_failed, and the TransactionStatus of the agreement itself says released. This means that you cannot rely on the Result parameter to determine whether the agreement was successfully paid for, but rather, you must look at the individual TransactionStatus parameters.

This means that if a charge fails, you can try to capture the payment at a later stage, without forcing your customer to create a new agreement.

You can use a credit card with number 4180000000001366 to trigger the failure.

                        <?xml version="1.0"?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-11-20T16:27:56+01:00</Date>
		<Path>API/reservation</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage/>
	</Header>
	<Body>
		<Result>Success</Result>
		<Transactions>
			<Transaction>
				<TransactionId>24045341</TransactionId>

				<PaymentId>96d3c1da-f813-4eb2-b291-58a5a690831b</PaymentId>
				<AuthType>subscriptionAndCharge</AuthType>
				<TransactionStatus>released</TransactionStatus>
				<ReservedAmount>250.00</ReservedAmount>
				<RecurringDefaultAmount>250.00</RecurringDefaultAmount>
			</Transaction>
			<Transaction>
				<TransactionId>24045351</TransactionId>
				<PaymentId>951b9526-cfdc-4f2e-9912-83e6b9ee085a</PaymentId>
				<AuthType>subscription_payment</AuthType>
				<TransactionStatus>captured_failed</TransactionStatus>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

When the agreement setup fails because the payment fails, the Result shows Failed, and the TransactionStatus is recurring_failed.

Here is an edited example of the XML response:

<?xml version="1.0"?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-11-20T16:48:59+01:00</Date>
		<Path>API/reservation</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage/>
	</Header>
	<Body>
		<Result>Failed</Result>
		<MerchantErrorMessage>TestAcquirer[pan=1466 or amount=14660]</MerchantErrorMessage>
		<CardHolderErrorMessage>Card Declined</CardHolderErrorMessage>
		<CardHolderMessageMustBeShown>false</CardHolderMessageMustBeShown>
		<Transactions>
			<Transaction>
				<TransactionId>24045611</TransactionId>
				<PaymentId>f9cc991a-a77a-42c8-9434-8fdd0f05a91b</PaymentId>
				<AuthType>subscriptionAndCharge</AuthType>
				<CardStatus>SoonExpired</CardStatus>
				<CreditCardExpiry>
					<Year>2017</Year>
					<Month>11</Month>
				</CreditCardExpiry>
				<CreditCardToken>33711c0f5a429e2065c4e1e5d5496b35b5a13af5</CreditCardToken>
				<CreditCardMaskedPan>413000******1466</CreditCardMaskedPan>
				<ThreeDSecureResult>Not_Attempted</ThreeDSecureResult>
				<LiableForChargeback>Merchant</LiableForChargeback>
				<CVVCheckResult>Not_Attempted</CVVCheckResult>
				<BlacklistToken>d73dad45c5934735899faf5465d1b37cfb1cb118</BlacklistToken>
				<ShopOrderId>4305925</ShopOrderId>
				<Shop>Sander Improvement Software AB</Shop>
				<Terminal>Sander Improvement Software AB Test Terminal</Terminal>
				<TransactionStatus>recurring_failed</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

When the agreement setup is done by calling /createPaymentRequest, you get a redirect response which contains the URL where to redirect the customer to the payment page.

For more details about the /createPaymentRequest method response, please see createPaymentRequest response section.

<?xml version="1.0"?>
<APIResponse version="20170228">
    <Header>
        <Date>2022-04-01T12:46:23+00:00</Date>
        <Path>API/createPaymentRequest</Path>
        <ErrorCode>0</ErrorCode>
        <ErrorMessage/>
    </Header>
    <Body>
        <Result>Success</Result>
        <PaymentRequestId>9ac6084e-c8dc-4e3b-b812-34857ed41ce2</PaymentRequestId>
        <Url>https://<YourShopName>/eCommerce/API/requestForm?pid=9ac6084e-c8dc-4e3b-b812-34857ed41ce2</Url>
        <DynamicJavascriptUrl>https://<YourShopName>/eCommerce/API/embeddedPaymentWindow?pid=9ac6084e-c8dc-4e3b-b812-34857ed41ce2</DynamicJavascriptUrl>
    </Body>
</APIResponse>

Visa decline reasons

Visa rules for merchants that are retrying declined transactions dependent on the decline message. Visa has 4 categories of decline reasons, for how merchants should be handling declined transactions. Please note that this is in relation to Visa cards.

Catagory of decline reason

Category 1

This category indicates that a card is blocked or never existed, meaning there is no circumstance under which the issuer will approve the transaction. There should be made No reattempt to authorise a transaction that has received a category-1 decline.

Category 2

This category indicates that the issuer may approve but cannot do so now due to a system issue or lack of cardholder funds. It is a temporary decline and may change over time and retry attempts. It is allowed up to 15 transaction reattempts per card in 30 days after receiving a category-2 decline.

Category 3

This category indicates that the issuer cannot approve the transaction based on the details provided, for example, due to an invalid account number, incorrect card verification value or expiration date. Up to 25,000 category-3 declines in 30 days per merchant is allowed.

Category 4

This category includes all decline codes which are not included in categories 1, 2 and 3. Only 15 transaction reattempts per card in 30 days after receiving a category-4 decline is allowed.

Visa decline reasons

Category 1

  • Pickup card
  • Pickup card, special conditions
  • Invalid transaction
  • No such issuer
  • Pickup card, lost card
  • Pickup card, stolen card
  • Transaction not permitted to cardholder
  • Transaction cannot be completed
  • Stop payment order
  • Revocation of authorization order
  • Revocation of all authorization

    • Category 2

  • Invalid merchant
  • Re-enter transaction
  • Insufficient funds
  • Suspected fraud
  • Blocked, first used
  • ATM malfunction
  • Issuer or switch is inoperative
  • Transaction cannot be completed - violation of law
  • Exceeds withdrawal amount limits
  • Restricted card - card invalid in region or country
  • Exceeds withdrawal frequency
  • Allowable number of PIN-entry tries exceeded
  • System malfunction
  • Cash request exceeds issuer limit
  • Cash service not available

    • Category 3

  • Invalid account number
  • Expired card
  • Incorrect PIN
  • Negative online CAM, dCVV, iCVV or CVV results
  • Decline for CVV2 failure (Visa)
  • additional customer authentication required
  • PIN data required

    • Category 4

  • All other decline reasons.

    • PBS decline error strings

    Category 1

  • Invalid transaction
  • Lost card
  • Stolen card
  • Transaction not permitted to cardholder

    • Category 2

  • Invalid merchant
  • Not sufficient funds
  • Re-enter transaction
  • Suspected fraud
  • Suspected Fraud
  • Exceeds withdrawal amount limit
  • Exceeds withdrawal frequency limit
  • Allowable number of pin tries exceede

    • Category 3

  • Expired card
  • Expired Card
  • Incorrect pin

    • Category 4

  • Acquirer not supported by switch
  • Allowable pin tries exceeded
  • Card Acceptor call Acquirers security department
  • Card acceptor call acquires security departmen
  • Card acceptor contact acquirer
  • Card entry found, below low range
  • Card not effective
  • CAVV Incorrect
  • Do not honour
  • Duplicate transmission
  • Encryption key error
  • Format error
  • Honour with identification
  • Invalid amount
  • Invalid card number
  • Invalid date
  • Invalid pin block
  • MAC incorrect
  • MAC key sync error
  • Match on previous transaction not allowe
  • No account of type requested
  • No card record
  • No communication keys available
  • Not able to trace back to original transaction
  • No valid conversion for a field
  • Pan length not according to table
  • Pin data required
  • Pin key synch error
  • Pin length error
  • Refer to card issuer
  • Refer to card issuer – special conditions
  • Requested function not supported
  • Restricted card
  • Security violation
  • Special conditions
  • Suspected counterfeit card
  • System malfunction
  • Transaction destination cannot find routing
  • Transaction not permitted to terminal
  • Unable to locate previous message
  • Unacceptable fee
  • Violation of business arrangement
  • Violation of law

    • Elavon decline reasons

    Category 1

  • Pick Up Card (no fraud)
  • Pick Up Card - special
  • Invalid Txn
  • Invalid Account Number
  • No such issuer
  • Lost card - pick up
  • Stolen card - pick up
  • Closed Account
  • Txn not permitted to C/H
  • Stop payment order
  • Revoc of auth order
  • Revoc of all auth orders

    • Category 2

  • Invalid Merchant
  • Re-enter txn
  • Insufficient Funds
  • Suspected Fraud
  • Exceeds Approval Amt Lmt
  • Restricted Card
  • Exceeds Withdraw al Freq Lmt
  • PIN Retries exceeded
  • Blocked First Used
  • Cannot Verify PIN
  • Issuer Unavilable
  • Txn cannot complete - law
  • System malfunction
  • Cash Service Not Avail
  • Cash Serv exceeds apprv lmt

    • Category 3

  • Invalid account number
  • Exp Card or missing exp date
  • Incorrect PIN
  • PIN Data Reqd
  • Neg online CVV results
  • Addtl cust authent reqd
  • Incorrect CVV

    • Category 4

  • All other decline reasons.

    • Please make sure you store the transaction_id in your system.

    The transactionId of the setup agreement transaction from the response will be sent as the agreement[id] parameter of the charge agreement request.